Files

Capture Edge accepts files, such as images or configuration files, over any protocol that carries strings.

A file is sent as a field value in the form of a data URI. The data URI either contains the base64 encoded contents of the file, or a path to a file that already exists on the device. A data URI with ;base64, before the data carries the file contents, and one with isfilepath=true carries a path. Without either, Capture Edge decodes the data as base64 when it can and treats it as a path otherwise. A path such as /mnt/drive1/file1.jpg contains a ., which base64 never does, but a path made only of letters, digits and /, such as /tmp/ab/img1, needs isfilepath=true.

warning

Not every file is synced to the cloud. In a new configuration, a file is synced unless its data URI says sync=false. In an existing configuration, a file is only synced when its data URI says sync=true. See Which files are synced.

RequiresCloud3.9.0+upcoming

From Capture Edge 2.3.1, a file is synced as a data URI in the time series data instead of through the FileToCloudQueue table. Gateways on an older Edge version keep using the queue.

From Capture Cloud 3.9.0, Capture Edge uploads large files in a single multipart request. With an older Capture Cloud, files are sent inline as before, so a file has to fit in one sync message.

The syntax to use when encoding the file in base64

data:{mimetype}[;ext={ext}][;dstpath={dstpath}][;sync={sync}];base64,{base64EncodedFile}

mimetypeRequired

Mimetype of the file. Example: text/plain. Without ext or dstpath, it decides the file extension: the usual extension for the mimetype (image/jpeg → jpg, text/plain → txt), or dat if the mimetype is unknown.

extOptional

The file extension to store the file with, such as jpg or tar.gz, with or without a leading dot. Only letters and digits, optionally separated by single dots, up to 16 characters; any other value is ignored and the extension follows the mimetype. Not used together with dstpath, which names the file itself.

dstpathOptional

The relative path where to store the file (both locally and in the cloud), including the file name and extension. If not provided, a random file name is generated in a folder named after the measurement.

syncOptional

true or false: whether the file is synced to the cloud. The default depends on the Collector's file field layout, see Which files are synced.

base64EncodedFileRequired

The Base64 encoded file.

Examples:

data:image/jpeg;base64,ABCDEF0123456789
data:image/jpeg;ext=jpeg;base64,ABCDEF0123456789
data:text/plain;dstpath=configFiles/myapp/config1.txt;base64,ABCDEF0123456789
data:image/jpeg;sync=true;base64,ABCDEF0123456789

The syntax to use when using file path

data:[{mimetype}][;dstpath={dstpath}][;createlocalcopy={createlocalcopy}][;sync={sync}][;isfilepath=true],{filePath}

mimetypeOptional

Mimetype of the file. Example: text/plain. If it is left empty, it is derived from the extension in filePath, or application/octet-stream if the extension is unknown.

dstpathOptional

The relative path where to store the file (both locally and in the cloud), including the file name and extension. If not provided, the local copy keeps the original file name with a unique suffix, in a folder named after the measurement.

createlocalcopyOptional

Edge2.3.1+ Overrides the global Copy Files To Local On Ingest setting for this file only. When true, the file is copied to the Capture data folder and synced from there; when false, the original file path is used for syncing. Default: the global setting.

syncOptional

true or false: whether the file is synced to the cloud. The default depends on the Collector's file field layout, see Which files are synced.

isfilepathOptional

true marks the data as a file path. Only needed for a path that could also be read as base64, such as /tmp/ab/img1.

filePathRequired

The path to the file, accessible for the collector service. With createlocalcopy=false, the syncer service must be able to read it too.

Examples:

data:image/jpeg,/mnt/drive1/file1.jpg
data:text/plain;dstpath=configFiles/myapp/config1.conf,C:\myapp\config\config.conf
data:image/jpeg;createlocalcopy=false,/mnt/drive1/file1.jpg
data:image/jpeg;sync=false,/mnt/drive1/file1.jpg
data:image/jpeg;isfilepath=true,/tmp/ab/img1

note

See Copy Files To Local On Ingest for the global setting and how it interacts with deleting local files after syncing.

If the file no longer exists when the syncer uploads the point, the field value is replaced by file-removed-before-syncing.

Metadata rules

• Keys are case-insensitive: dstpath and dstPath are the same key.
• Boolean values are true or false. Any other value, such as yes, is ignored and the default is used.
• dstpath must be relative. A path that contains .. is ignored, and a random path is used instead. An absolute path is rejected and the file is not extracted.
• Values cannot contain ;, , or =.
• Keys that Capture Edge does not know are ignored.
• ext applies to base64 encoded files only. A file path keeps the extension of the file it points to.

Which files are synced

RequiresEdge2.3.1+

Older Capture Edge versions always work like Suffixed.

Which files are synced, and the fields a file is stored under, depend on the Collector's fileFieldNaming setting. New configurations get InPlace. Existing configurations get Suffixed, the layout of Capture Edge 2.2, so flows built on it keep working. For a field named image:

fileFieldNaming	A file is synced when its data URI says	Fields stored and sent to the cloud
InPlace	anything but sync=false	image: the file.
Suffixed	sync=true	image_local: the path of the file on the gateway. For a synced file also image_cloud: the file, and image_mimetype: its mimetype.

A file that is not synced stays on the gateway, and is not deleted by Delete local files after syncing.

warning

Switching an existing configuration to InPlace changes the field the cloud receives files under, so dashboards that read image_cloud no longer find new files.

Blob store configuration

The gateway's company needs a blob store to keep these files in the cloud. See Blob Stores to set one up.